ADR (architecture decision records)
議論を記錄する
仕樣書ではない
An Architectural Decision (AD) is a justified software design choice addressing a functional or non-functional requirement that is architecturally significant. アーキテクチャ上の決定とは、アーキテクチャとして重要な機能要件や非機能要件について、ソフトウェアを設計する上でなされた選擇です。
An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. アーキテクチャとして重要な要件とは、ソフトウェアやハードウェアのシステムに對して、アーキテクチャや品質に測定可能な影響を與へるものを言ひます。
MADR (Markdown ADR) template
https://gyazo.com/7aca146674f38e0bc97f9b7cda351330
MADR light
https://gyazo.com/0ffda271cdc2c9328b3a380da096e9ae
title
問題の本質 + 選擇された解決策
metadata
status
proposed | rejected | accepted | deprecated | … | superseded by
date
最終更新日
deciders
決定者
consulted
相談を受けた人
informed
context and problem statement
狀況と問題
決定によって解決する問題
決定に關係する現狀
decision drivers
要求
選擇肢を制約する要求
considered options
選擇肢
title 狀のものを列擧するに留める
詳細は "chosen option" と "pros and cons of the option" で書く
chosen option
決定
decision outcome (with justification)
理由
consequences (good, bad)
狀況と問題がどう變はるか
validation (review, test)
どうやって決定を遂行するか
どうやって決定の遂行を保證するか
pros and cons of the option
利點と缺點
代替案との比較
more information
format
title
architecture 決定の簡單な說明
status
期限附き RFC (request for comment)、提案濟み、承認濟み、破棄
context
この決定を行った狀況
課題
現狀
決定を考案する際の制約
決定
決定とその根據 (why)
影響
この決定による影響。trade-off
compliance
この決定が遵守されてゐることを確認する方法
代替案
備考
この決定の meta data
original の著者
承認日
承認者
置き換へ日
最終更新日
變更點
最終更新內容
adr-tools
CALM (冷靜さ)
Collaborative content creation is enabled. 協働
Accountability is supported. 責任
Learning opportunities are provided, both for newcomers and for the experienced. 學習の機會
Management likes them too because it is used to making and executing decisions. 經營
Good
Select by priority and significance.
Do not defer making and capturing high-impact decisions for too long (in the name of flexibility).
prioritize meta-qualities such as observability and ability to react
Root and justify decision in actual requirements and personal experience.
Invest in editorial quality, having an eye on the appropriate ADR length.
Split decisions into stages if no simple answer exist.
Disclose your confidence level.
Bad
subjectivity creeping in
Fairy Tale (aka Wishful Thinking)
Sales Pitch
Free Lunch Coupon (aka Candy Bar)
Dummy Alternative
the time dimension of architecting
Sprint (aka Rush)
Tunnel Vision
Maze
record size and content nature
Blueprint or Policy in Disguise
Mega-ADR
Novel and epic
Magic Tricks ("AD wizardry")
Non-existing or misleading context information to create a false sense of urgency.
Problem-solution mismatch
Pseudo-accuracy
批判。批評
Good
scope
Deliver what is asked for.
Prioritize comments by urgency and importance
Document the scope and the goals of the review
Document the scope and the goals of the review
content
Justify comments and calls to actions by referencing desired qualities
Acknowledge context and requirements
Be concrete and factual in option judgments.
commenting style
Comment in a problem- and solution-oriented way.
Report your perception/impressions, but do not interpret or guess.
Be at least as factual, thorough and focused as the ADR that is reviewed
Criticize as strongly as needed, but also be motivating.
Be fair and polite.
actionability
Make the feedback resolvable
Offer help with comment resolution.
Review the review comments
Bad
Pass Through
Copy Edit
Siding, Dead End (aka Excursion)
Self Promotion, Conflict of Interest
Power Game
Offended Reaction
Groundhog Day